=over

=item getpwnam NAME
X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent>
X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
X<endnetent> X<endprotoent> X<endservent>

=item getgrnam NAME

=item gethostbyname NAME

=item getnetbyname NAME

=item getprotobyname NAME

=item getpwuid UID

=item getgrgid GID

=item getservbyname NAME,PROTO

=item gethostbyaddr ADDR,ADDRTYPE

=item getnetbyaddr ADDR,ADDRTYPE

=item getprotobynumber NUMBER

=item getservbyport PORT,PROTO

=item getpwent

=item getgrent

=item gethostent

=item getnetent

=item getprotoent

=item getservent

=item setpwent

=item setgrent

=item sethostent STAYOPEN

=item setnetent STAYOPEN

=item setprotoent STAYOPEN

=item setservent STAYOPEN

=item endpwent

=item endgrent

=item endhostent

=item endnetent

=item endprotoent

=item endservent

These routines are the same as their counterparts in the
system C library.  In list context, the return values from the
various get routines are as follows:

 #    0        1          2           3         4
 my ( $name,   $passwd,   $gid,       $members  ) = getgr*
 my ( $name,   $aliases,  $addrtype,  $net      ) = getnet*
 my ( $name,   $aliases,  $port,      $proto    ) = getserv*
 my ( $name,   $aliases,  $proto                ) = getproto*
 my ( $name,   $aliases,  $addrtype,  $length,  @addrs ) = gethost*
 my ( $name,   $passwd,   $uid,       $gid,     $quota,
    $comment,  $gcos,     $dir,       $shell,   $expire ) = getpw*
 #    5        6          7           8         9

(If the entry doesn't exist, the return value is a single meaningless true
value.)

The exact meaning of the $gcos field varies but it usually contains
the real name of the user (as opposed to the login name) and other
information pertaining to the user.  Beware, however, that in many
system users are able to change this information and therefore it
cannot be trusted and therefore the $gcos is tainted (see
L<perlsec>).  The $passwd and $shell, user's encrypted password and
login shell, are also tainted, for the same reason.

In scalar context, you get the name, unless the function was a
lookup by name, in which case you get the other thing, whatever it is.
(If the entry doesn't exist you get the undefined value.)  For example:

    my $uid   = getpwnam($name);
    my $name  = getpwuid($num);
    my $name  = getpwent();
    my $gid   = getgrnam($name);
    my $name  = getgrgid($num);
    my $name  = getgrent();
    # etc.

In I<getpw*()> the fields $quota, $comment, and $expire are special
in that they are unsupported on many systems.  If the
$quota is unsupported, it is an empty scalar.  If it is supported, it
usually encodes the disk quota.  If the $comment field is unsupported,
it is an empty scalar.  If it is supported it usually encodes some
administrative comment about the user.  In some systems the $quota
field may be $change or $age, fields that have to do with password
aging.  In some systems the $comment field may be $class.  The $expire
field, if present, encodes the expiration period of the account or the
password.  For the availability and the exact meaning of these fields
in your system, please consult L<getpwnam(3)> and your system's
F<pwd.h> file.  You can also find out from within Perl what your
$quota and $comment fields mean and whether you have the $expire field
by using the L<C<Config>|Config> module and the values C<d_pwquota>, C<d_pwage>,
C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>.  Shadow password
files are supported only if your vendor has implemented them in the
intuitive fashion that calling the regular C library routines gets the
shadow versions if you're running under privilege or if there exists
the L<shadow(3)> functions as found in System V (this includes Solaris
and Linux).  Those systems that implement a proprietary shadow password
facility are unlikely to be supported.

The $members value returned by I<getgr*()> is a space-separated list of
the login names of the members of the group.

For the I<gethost*()> functions, if the C<h_errno> variable is supported in
C, it will be returned to you via L<C<$?>|perlvar/$?> if the function
call fails.  The
C<@addrs> value returned by a successful call is a list of raw
addresses returned by the corresponding library call.  In the
Internet domain, each address is four bytes long; you can unpack it
by saying something like:

    my ($w,$x,$y,$z) = unpack('W4',$addr[0]);

The Socket library makes this slightly easier:

    use Socket;
    my $iaddr = inet_aton("127.1"); # or whatever address
    my $name  = gethostbyaddr($iaddr, AF_INET);

    # or going the other way
    my $straddr = inet_ntoa($iaddr);

In the opposite way, to resolve a hostname to the IP address
you can write this:

    use Socket;
    my $packed_ip = gethostbyname("www.perl.org");
    my $ip_address;
    if (defined $packed_ip) {
        $ip_address = inet_ntoa($packed_ip);
    }

Make sure L<C<gethostbyname>|/gethostbyname NAME> is called in SCALAR
context and that its return value is checked for definedness.

The L<C<getprotobynumber>|/getprotobynumber NUMBER> function, even
though it only takes one argument, has the precedence of a list
operator, so beware:

    getprotobynumber $number eq 'icmp'   # WRONG
    getprotobynumber($number eq 'icmp')  # actually means this
    getprotobynumber($number) eq 'icmp'  # better this way

If you get tired of remembering which element of the return list
contains which return value, by-name interfaces are provided in standard
modules: L<C<File::stat>|File::stat>, L<C<Net::hostent>|Net::hostent>,
L<C<Net::netent>|Net::netent>, L<C<Net::protoent>|Net::protoent>,
L<C<Net::servent>|Net::servent>, L<C<Time::gmtime>|Time::gmtime>,
L<C<Time::localtime>|Time::localtime>, and
L<C<User::grent>|User::grent>.  These override the normal built-ins,
supplying versions that return objects with the appropriate names for
each field.  For example:

   use File::stat;
   use User::pwent;
   my $is_his = (stat($filename)->uid == pwent($whoever)->uid);

Even though it looks as though they're the same method calls (uid),
they aren't, because a C<File::stat> object is different from
a C<User::pwent> object.

Many of these functions are not safe in a multi-threaded environment
where more than one thread can be using them.  In particular, functions
like C<getpwent()> iterate per-process and not per-thread, so if two
threads are simultaneously iterating, neither will get all the records.

Some systems have thread-safe versions of some of the functions, such as
C<getpwnam_r()> instead of C<getpwnam()>.  There, Perl automatically and
invisibly substitutes the thread-safe version, without notice.  This
means that code that safely runs on some systems can fail on others that
lack the thread-safe versions.

Portability issues: L<perlport/getpwnam> to L<perlport/endservent>.

=back